@Part[Progs, Root = "CLM.MSS"]
@Comment{Chapter of Spice Lisp Manual.  Copyright 1984 Guy L. Steele Jr.⎇


@MyChapter[Program Structure]
@Label[PROGS]

In chapter @ref[DTYPES] the syntax was sketched for notating data objects
in @clisp.  The same syntax is used for notating programs because all
@clisp programs have a representation as @clisp data objects.

@xlisp programs are organized as forms and functions.  Forms are
@i[evaluated] (relative to some context) to produce values and side
effects.  Functions are invoked by @i[applying] them to arguments.
The most important kind of form performs a function call;
conversely, a function performs computation by evaluating forms.

In this chapter forms are discussed first, and then functions.
Finally, certain ``top level'' special forms are discussed; the most
important of these is @f[defun], whose purpose is to define a
named function.

@Section[Forms]

The standard unit of interaction with a @clisp implementation is the @i[form],
which is simply a data object meant to be @i[evaluated] as a program
to produce one or more @i[values] (which are also data objects).
One may request evaluation of @i[any] data object, but only certain ones
are meaningful.  For instance,
symbols and lists are meaningful forms, while arrays
normally are not.  Examples of meaningful forms are @f[3],
whose value is @f[3], and @f[(+ 3 4)], whose value is @f[7].
We write @f[3] @EV @f[3] and @f[(+ 3 4)] @EV @f[7]
to indicate these facts.  (@EV means ``evaluates to.'')

Meaningful forms may be divided into three categories:
self-evaluating forms, such as numbers; symbols, which stand
for variables; and lists.  The lists in turn may be divided
into three categories: special forms, macro calls, and function calls.

Any @clisp data object not explicitly defined here to be a valid form
is not a valid form.  It is an error to evaluate
anything but a valid form.
@Implementation{An implementation is free to make
implementation-dependent extensions to the evaluator, but is
strongly encouraged to signal an error on any attempt to
evaluate anything but a valid form or an object for which
a meaningful evaluation extension has been purposely defined.⎇

@Subsection[Self-Evaluating Forms]

All numbers, characters, strings, and bit-vectors
are @i[self-evaluating] forms.
When such an object is evaluated, that object
(or possibly a copy in the case of numbers) is returned as the value
of the form.  The empty list @empty, which is also the false value @false,
is also a self-evaluating form: the value of @false is @false.
Keywords (symbols written with a leading colon) also evaluate
to themselves: the value of @Kwd[start] is @Kwd[start].

@Subsection[Variables]

Symbols are used as names of variables in @clisp programs.
When a symbol is evaluated as a form, the value of the variable it names
is produced.  For example, after doing @f[(setq items 3)], which assigns
the value @f[3] to the variable named @f[items], then @f[items] @EV @f[3].
Variables can be @i[assigned] to, as by @Specref[setq], or @i[bound],
as by @Specref[let].
Any program construct that binds a variable effectively saves the old
value of the variable and causes it to have a new value, and on exit from
the construct the old value is reinstated.

There are actually two kinds of variables in @clisp, called @i[lexical] (or
@i[static]) variables and @i[special] (or @i[dynamic]) variables.
At any given time either or both kinds of variable with the same name may
have a current value.  Which of the two kinds of variable is referred to
when a symbol is evaluated depends on the context of the evaluation.
The general rule is that if the symbol occurs textually within a program
construct that creates a @i[binding] for a variable of the same name,
then the reference is to the variable specified by the binding;
if no such program construct textually contains the reference, then
it is taken to refer to the special variable of that name.

The distinction between the two kinds of variable is one of scope
and extent.  A lexically bound variable can be referred to @i[only]
by forms occurring at any @i[place] textually within the program construct that
binds the variable.  A dynamically bound (special) variable can
be referred to at any @i[time] from the time the binding is made
until the time evaluation of the construct that binds the variable
terminates.  Therefore lexical binding of variables
imposes a spatial limitation
on occurrences of references (but no temporal limitation, for the
binding continues to exist as long as the possibility of reference
remains).  Conversely, dynamic binding of variables imposes a temporal
limitation on occurrences of references (but no spatial limitation).
For more information on scope and extent, see chapter @ref[SCOPE].

The value a special variable has when there are currently
no bindings of that variable is called the @i[global] value of the
(special) variable.
A global value can be given to a variable only by assignment,
because a value given by binding is by definition not global.

It is possible for a special variable to have no value at all,
in which case it is said to be @i[unbound].
By default, every global variable is unbound unless and until
explicitly assigned a value, except for those global variables
defined in this manual or by the implementation already to have values
when the @xlisp system is first started.
It is also possible to establish a binding of a special variable
and then cause that binding to be valueless by using the
function @Funref[makunbound].  In this situation the variable
is also said to be ``unbound,'' although this is a misnomer;
precisely speaking, it is bound but valueless.
It is an error to refer to a variable that is unbound.

Certain global variables are reserved as ``named constants.''
They have a global value and may not be bound or assigned to.
For example,
the symbols @true and @false are reserved.
One may not assign a value to @true or @false,
and one may not bind @true or @false.  The global value of
@true is always @true, and the global value of
@false is always @false.  Constant symbols defined by
@Macref[defconstant] also become reserved and may not be further
assigned to or bound (although they may be redefined, if necessary, by
using @f[defconstant] again).  Keyword symbols,
which are notated with a leading colon, are reserved and
may never be assigned to or bound; a keyword always evaluates
to itself.

@Subsection[Special Forms]

If a list is to be evaluated as a form, the first step is to examine
the first element of the list.  If the first element is one of
the symbols appearing in Table @Ref[Special-Form-Table],
then the list is called a @i[special form].  (This use of the word
``special'' is unrelated to its use in the phrase ``special variable.'')
@Begin[Table]
@Mline[]
@Caption[Names of All @clisp Special Forms]
@Tag[Special-Form-Table]
@Lisp
@Tabset[+1.5in,+2in]
@f[block]@\@f[if]@\@f[progv]
@f[catch]@\@f[labels]@\@f[quote]
@f[compiler-let]@\@f[let]@\@f[return-from]
@f[declare]@\@f[let*]@\@f[setq]
@f[eval-when]@\@f[macrolet]@\@f[tagbody]
@f[flet]@\@f[multiple-value-call]@\@f[the]
@f[function]@\@f[multiple-value-prog1]@\@f[throw]
@f[go]@\@f[progn]@\@f[unwind-protect]
@Endlisp
@Mline[]
@End[Table]

Special forms are generally environment and control constructs.
Every special form has its own idiosyncratic syntax.  An example
is the @f[if] special form:
@f[(if p (+ x 4) 5)] in @clisp means what
``@b[if] @i[p] @b[then] @i[x]+4 @b[else] 5'' would mean in @algol.

The evaluation of a special form normally produces a value or values,
but it may instead call for a non-local exit; see @Specref[return-from],
@Specref[go], and @Specref[throw].

The set of special forms is fixed in @clisp; no way is provided
for the user to define more.  The user can create new syntactic
constructs, however, by defining macros.

The set of special forms in @clisp is purposely kept very small
because any program-analyzing program must have special knowledge
about every type of special form.  Such a program needs no special
knowledge about macros because it is simple to expand the macro
and operate on the resulting expansion.  (This is not to say that
many such programs, particularly compilers, will not have such
special knowledge.  A compiler may be able
to produce much better code if it recognizes such constructs
as @f[typecase] and @f[multiple-value-bind] and gives them customized
treatment.)

An implementation is free to implement as a macro any construct described
herein as a special form.  Conversely, an implementation is free
to implement as a special form any construct described herein as a macro
if an equivalent macro definition is also provided.
The practical consequence is that the predicates @Funref[macro-function] and
@f[special-form-p] may both be true of the same symbol.
It is recommended that a program-analyzing program process
a form that is a list whose @i[car] is a symbol as follows:
@Begin[Enumerate]
If the program has particular knowledge about the symbol,
process the form using special-purpose code.
All of the symbols listed in Table @ref[SPECIAL-FORM-TABLE]
should fall into this category.

Otherwise, if @f[macro-function] is true of the symbol, apply either
@Funref[macroexpand] or @f[macroexpand-1], as appropriate,
to the entire form and then start over.

Otherwise, assume it is a function call.
@End[Enumerate]

@Subsection[Macros]

If a form is a list and the first element is not the name of a special
form, it may be the name of a @i[macro]; if so, the form is said
to be a @i[macro call].  A macro is essentially a function from
forms to forms that will, given a call to that macro, compute
a new form to be evaluated in place of the macro call.
(This computation is sometimes referred to as @i[macro expansion].)
For example, the macro named @Macref[return] will take a form such as
@f[(return x)] and from that form compute a new form
@f[(return-from @nil x)].  We say that the old
form @i[expands] into the new form.  The new form is then evaluated in
place of the original form; the value of the new form is returned as the
value of the original form.

There are a number of standard macros in @clisp, and the user can define more
by using @Macref[defmacro].

Macros provided by a @clisp implementation as described herein may expand
into code that is not portable among differing implementations.
That is, a macro call may be implementation-independent because
the macro is defined in this manual, but the expansion need not be.
@Implementation{Implementors are encouraged to implement the macros
defined in this manual, as far as is possible, in such as way that
the expansion will not contain any implementation-dependent
special forms, nor contain as forms data objects that
are not considered to be forms in @clisp.
The purpose of this restriction is to ensure that the expansion
can be processed by a program-analyzing program in an
implementation-independent manner.
There is no problem with a macro expansion containing
calls to implementation-dependent functions.
This restriction is not a requirement of @clisp; it is recognized
that certain complex macros may be able to expand into significantly
more efficient code in certain implementations
by using implementation-dependent special forms in the macro expansion.⎇

@Subsection[Function Calls]

If a list is to be evaluated as a form and the first element is
not a symbol that names a special form or macro, then the list
is assumed to be a @i[function call].  The first element of the
list is taken to name a function.  Any and all remaining elements
of the list are forms to be evaluated; one value is obtained
from each form,
and these values become the @i[arguments] to the function.
The function is then @i[applied] to the arguments.
The functional computation normally produces a value,
but it may instead call for a non-local exit; see @Specref[throw].
A function that does return may produce no value or several values;
see @Funref[values].
If and when the function returns, whatever values it returns
become the values of the function-call form.


For example, consider the evaluation of the form @f[(+ 3 (* 4 5))].
The symbol @f[+] names the addition function, not a special form or macro.
Therefore the two forms @f[3] and @f[(* 4 5)] are evaluated to produce
arguments.  The form @f[3] evaluates to @f[3], and the form
@f[(* 4 5)] is a function call (to the multiplication function).
Therefore the forms @f[4] and @f[5] are evaluated, producing arguments
@f[4] and @f[5] for the multiplication.  The multiplication function
calculates the number @f[20] and returns it.  The values @f[3] and @f[20]
are then given as arguments to the addition function, which calculates
and returns the number @f[23].  Therefore we say @f[(+ 3 (* 4 5)) @EV 23].

@Section[Functions]

There are two ways to indicate a function to be used in a function call
form.  One is to use a symbol that names the function.  This use of
symbols to name functions is completely independent of their use in
naming special and lexical variables.  The other way is to use a
@i[lambda-expression], which is a list whose first element is the symbol
@f[lambda].  A lambda-expression is @i[not] a form; it cannot be
meaningfully evaluated.  Lambda-expressions and symbols, when used in
programs as names of functions, can appear only as the first element of a
function-call form, or as the second element of the @Specref[function]
special form.  Note that symbols and lambda-expressions are treated as
@i[names] of functions in these two contexts.  This should be
distinguished from the treatment of symbols and lambda-expressions as
@i[function objects], that is,
objects that satisfy the predicate @Funref[functionp],
as when giving such an object to @Funref[apply] or @Funref[funcall] to be
invoked.

@Subsection[Named Functions]

A name can be given to a function in one of two ways.
A @i[global name] can be given to a function by using the
@Macref[defun] construct.
A @i[local name] can be given to a function by using the
@Specref[flet] or
@Specref[labels] special form.
When a function is named, a lambda-expression is effectively
associated with that name
along with information about the entities that are lexically apparent
at that point.
If a symbol appears as the first element of a function-call form, then it
refers to the definition established by the innermost @f[flet] or @f[labels]
construct that textually contains the reference, or to the global
definition (if any) if there is no such containing construct.

@Subsection[Lambda-Expressions]
@label[LAMBDA-EXPRESSIONS-SECTION]
@index[lambda-expression]

A @i[lambda-expression] is a list with the following syntax:
@Lisp
(lambda @i[lambda-list] . @i[body])
@Endlisp
The first element must be the symbol @f[lambda].  The second element
must be a list.  It is called the @i[lambda-list], and specifies
names for the @i[parameters] of the function.  When the function
denoted by the lambda-expression is applied to arguments,
the arguments are matched with the parameters specified by the
lambda-list.  The @i[body] may then refer to the arguments by using
the parameter names.  The @i[body] consists of any number of
forms (possibly zero).  These forms are evaluated in sequence,
and the results of the @i[last] form only are returned as the results
of the application (the value @false is returned if there are zero
forms in the body).

The complete syntax of a lambda-expression is:
@Commandstring[GrossOptVars = "@Mstar<@i[var] @Mor (@i[var] @Mopt{@i[initform] @mopt'@i[svar]'⎇)>"]
@Commandstring[GrossKeyOptVars = "@Mstar<@i[var] @Mor (@Mgroup{@i[var] @Mor (@i[keyword] @i[var])⎇ @Mopt{@i[initform] @mopt'@i[svar]'⎇)>"]
@Commandstring[GrossAuxVars = "@Mstar{@i[var] @mor (@i[var] @Mopt'@i[initform]')⎇"]
@Lisp
(lambda (@Mstar<@i[var]>
         @mopt{@optional @GrossOptVars⎇
	 @mopt{@rest @i[var]⎇
         @mopt[@key @!@GrossKeyOptVars
	    @/@mopt[@allowotherkeys]]
         @Mopt<@aux @GrossAuxVars>)
   @Mstar<@i[declaration] @Mor @i[documentation-string]>
   @Mstar<@i[form]>)
@Endlisp
Each element of a lambda-list is either a @i[parameter specifier]
or a @i[lambda-list keyword]; lambda-list keywords begin with @f[&].
(Note that lambda-list keywords are not keywords in the usual sense;
they do not belong to the keyword package.  They are ordinary symbols
each of whose names begins with an ampersand.  This terminology
is unfortunately confusing but is retained for historical reasons.)

In all cases a @i[var] or @i[svar] must be a symbol, the name of a variable;
each @i[keyword] must be a keyword symbol, such as @Kwd[start].
An @i[initform] may be any form.

A lambda-list has five parts, any or all of which may be empty:
@Begin[Itemize]
Specifiers for the @i[required] parameters.  These are all the parameter
specifiers up to the first lambda-list keyword; if there is no such
lambda-list keyword, then all the specifiers are for required parameters.

Specifiers for @i[optional] parameters.
If the lambda-list keyword @optional is present,
the @i[optional] parameter specifiers are those following the
lambda-list keyword @optional up to the next lambda-list keyword or the end of the list.

A specifier for a @i[rest] parameter.  The lambda-list keyword @rest, if present, must
be followed by a single @i[rest] parameter specifier,
which in turn must be followed by another lambda-list keyword or the end
of the lambda-list.

Specifiers for @i[keyword] parameters.
If the lambda-list keyword @key is present, all specifiers up to the next lambda-list keyword
or the end of the list are @i[keyword] parameter specifiers.
The keyword parameter specifiers may optionally be followed by the
lambda-list keyword @allowotherkeys.

Specifiers for @i[aux] variables.  These are not really parameters.
If the lambda-list keyword @aux is present, all specifiers after it are
@i[auxiliary variable] specifiers.
@End[Itemize]

When the function represented by the lambda-expression is applied
to arguments, the arguments and parameters are processed in order
from left to right.
In the simplest case, only required parameters are present
in the lambda-list; each is specified simply by a name @i[var] for
the parameter variable.
When the function is applied,
there must be exactly as many arguments as there are parameters,
and each parameter is bound to one argument.  Here, and in general,
the parameter is bound as a lexical variable unless a
declaration has been made that it should be a special binding;
see @Macref[defvar], @Funref[proclaim], and @Specref[declare].

In the more general case, if there are @i[n] required parameters
(@i[n] may be zero), there must be at least @i[n] arguments,
and the required parameters are bound to the first @i[n] arguments.
The other parameters are then processed using any remaining arguments.

If @i[optional] parameters are specified, then each one is processed as
follows.  If any unprocessed arguments remain, then the parameter variable
@i[var] is bound to the next remaining argument, just as for a required
parameter.  If no arguments remain, however, then the @i[initform] part
of the parameter specifier is evaluated, and the parameter variable
is bound to the resulting value (or to @false if no @i[initform] appears
in the parameter specifier).
If another variable name @i[svar] appears in the specifier, it is bound
to @i[true] if an argument was available, and to @i[false] if no
argument remained (and therefore @i[initform] had to be evaluated).
The variable @i[svar] is called a @i[supplied-p] parameter;
it is bound not to an argument but to a value indicating whether or not
an argument had been supplied for another parameter.

After all @i[optional] parameter specifiers have been processed,
then there may or may not be a @i[rest] parameter.
If there is a @i[rest] parameter, it is bound to a list of all
as-yet-unprocessed arguments.  (If no unprocessed arguments remain,
the @i[rest] parameter is bound to the empty list.)
If there is no @i[rest] parameter and there are no @i[keyword]
parameters,
then there should be no unprocessed arguments (it is an error if there are).

Next, any @i[keyword] parameters are processed.
For this purpose the same arguments are processed that
would be made into a list for a @i[rest] parameter.
(Indeed, it is permitted to specify both @rest and @key.
In this case the remaining arguments are used for both purposes;
that is, all remaining arguments are made into a list for the
@rest parameter, and are also processed for the @key parameters.
This is the only situation in which an argument is used
in the processing of more than one parameter specifier.)
If @key is specified, there must remain
an even number of arguments; these are considered as pairs,
the first argument in each pair being interpreted as a keyword name
and the second as the corresponding value.
It is an error for the first object of each pair to be
anything but a keyword.
@Rationale{This last restriction is imposed so that a compiler may
issue warnings about certain malformed calls to functions
that take keyword arguments.  It must be remembered that the
arguments in a function call that evaluate to keywords are just
like any other arguments, and may be any evaluable forms.
A compiler could not, without additional context, issue a warning
about the call
@lisp
(fill seq item x y)
@endlisp
because in principle the variable @f[x] might have as its value a keyword
such as @Kwd[start].  However, a compiler would be justified in issuing
a warning about the call
@lisp
(fill seq item 0 10)
@endlisp
because the constant @f[0] is definitely not a keyword.  Similarly,
if in the first case the variable @f[x] had been declared to be
of type @f[integer] then type analysis could enable the compiler
to justify a warning.⎇

In each keyword parameter specifier must be a name @i[var] for the
parameter variable.  If an explicit @i[keyword] is
specified, then that is the keyword name for the parameter.  Otherwise
the name @i[var] serves to indicate the keyword name,
in that a keyword with the same name (in the @f[keyword] package) is used
as the keyword.  Thus
@Lisp
(defun foo (@key radix (type 'integer)) ...)
@Endlisp
means exactly the same as
@Lisp
(defun foo (@key ((:radix radix)) ((:type type) 'integer)) ...)
@Endlisp
The keyword parameter specifiers are, like all parameter specifiers,
effectively processed from left to right.
For each keyword parameter specifier, if there is an argument
pair whose keyword name matches that specifier's keyword name
(that is, the names are @f[eq]),
then the parameter variable for that specifier is bound to the
second item (the value) of that argument pair.
If more than one such argument pair matches, it is not an error;
the leftmost argument pair is used.
If no such argument pair exists, then
the @i[initform] for that specifier is evaluated
and the parameter variable is bound to that value (or to @false if
no @i[initform] was specified).  The variable @i[svar] is treated
as for ordinary @i[optional] parameters: it is bound to @i[true]
if there was a matching argument pair, and to @i[false] otherwise.

It is an error if an argument pair has a keyword name not matched
by any parameter specifier, unless at least one of the following
two conditions is met:
@Begin[Itemize]
@allowotherkeys was specified in the lambda-list.

Among the keyword argument pairs is a pair whose keyword
is @Kwd[allow-other-keys] and whose value is not @false.
@End[Itemize]
If either condition obtains, then it is not an error
for an argument pair to match no parameter specified,
and the argument pair is simply ignored (but such an
argument pair is accessible through the @rest parameter if
one was specified).  The purpose of these mechanisms is to
allow sharing of argument lists among several functions
and to allow either the caller or the called function
to specify that such sharing may be taking place.

After all parameter specifiers have been processed, the auxiliary
variable specifiers (those following the lambda-list keyword @aux) are processed from
left to right.  For each one, the @i[initform] is evaluated and the
variable @i[var] bound to that value (or to @false if no @i[initform] was
specified).  Nothing can be done with @aux variables that cannot be
done with the special form @Specref[let*]:
@lisp
(lambda (x y @aux (a (car x)) (b 2) c) ...)
   @EQ (lambda (x y) (let* ((a (car x)) (b 2) c) ...))
@endlisp
Which to use is purely a matter of style.

Whenever any @i[initform] is evaluated for any parameter
specifier, that form may refer to any parameter variable to the left of
the specifier in which the @i[initform] appears, including any supplied-p
variables, and may rely on the fact that no other parameter variable
has yet been bound (including its own parameter variable).

Once the lambda-list has been processed, the forms in the body of the
lambda-expression are executed.  These forms may refer to the arguments
to the function by using the names of the parameters.  On exit from the
function, either by a normal return of the function's value(s) or by a
non-local exit, the parameter bindings, whether lexical or special, are
no longer in effect.  (The bindings are not necessarily permanently discarded,
for a lexical binding can later be reinstated if a
``closure'' over that binding was created,
perhaps by using @Specref[function], and saved before the exit occurred).

Examples of @optional and @rest parameters:
@Lisp
((lambda (a b) (+ a (* b 3))) 4 5) @EV 19
((lambda (a @optional (b 2)) (+ a (* b 3))) 4 5) @EV 19
((lambda (a @optional (b 2)) (+ a (* b 3))) 4) @EV 10
((lambda (@optional (a 2 b) (c 3 d) @rest x) (list a b c d x)))
   @EV (2 @false 3 @false @false)
((lambda (@optional (a 2 b) (c 3 d) @rest x) (list a b c d x)) 6)
   @EV (6 t 3 @false @false)
((lambda (@optional (a 2 b) (c 3 d) @rest x) (list a b c d x)) 6 3)
   @EV (6 t 3 t @false)
((lambda (@optional (a 2 b) (c 3 d) @rest x) (list a b c d x))
 6 3 8)
   @EV (6 t 3 t (8))
((lambda (@optional (a 2 b) (c 3 d) @rest x) (list a b c d x))
 6 3 8 9 10 11)
   @EV (6 t 3 t (8 9 10 11))
@Endlisp
Examples of @key parameters:
@Lisp
((lambda (a b @key c d) (list a b c d)) 1 2) @EV (1 2 @nil @nil)
((lambda (a b @key c d) (list a b c d)) 1 2 :c 6) @EV (1 2 6 @nil)
((lambda (a b @key c d) (list a b c d)) 1 2 :d 8) @EV (1 2 @nil 8)
((lambda (a b @key c d) (list a b c d)) 1 2 :c 6 :d 8) @EV (1 2 6 8)
((lambda (a b @key c d) (list a b c d)) 1 2 :d 8 :c 6) @EV (1 2 6 8)
((lambda (a b @key c d) (list a b c d)) :a 1 :d 8 :c 6) @EV (:a 1 6 8)
((lambda (a b @key c d) (list a b c d)) :a :b :c :d)
   @EV (:a :b :d @nil)
@Endlisp
Examples of mixtures:
@lisp
((lambda (a @optional (b 3) @rest x @key c (d a))
   (list a b c d x))
 1)   @EV (1 3 @nil 1 ())

((lambda (a @optional (b 3) @rest x @key c (d a))
   (list a b c d x))
 1 2)   @EV (1 2 @nil 1 ())

((lambda (a @optional (b 3) @rest x @key c (d a))
   (list a b c d x))
 :c 7)   @EV (:c 7 @nil :c ())

((lambda (a @optional (b 3) @rest x @key c (d a))
   (list a b c d x))
 1 6 :c 7)   @EV (1 6 7 1 (:c 7))

((lambda (a @optional (b 3) @rest x @key c (d a))
   (list a b c d x))
 1 6 :d 8)   @EV (1 6 @nil 8 (:d 8))

((lambda (a @optional (b 3) @rest x @key c (d a))
   (list a b c d x))
 1 6 :d 8 :c 9 :d 10)   @EV (1 6 9 8 (:d 8 :c 9 :d 10))
@endlisp

All lambda-list keywords are permitted, but not terribly useful, in
lambda-expressions appearing explicitly as the first element of a
function-call form.  They are extremely
useful, however, in functions given global names by @Macref[defun].

All symbols whose names begin with @f[&] are conventionally reserved
for use as lambda-list keywords and should not be used as variable names.
Implementations of @clisp are free to provide additional lambda-list
keywords.

@Defcon[Var {lambda-list-keywords⎇]
The value of @f[lambda-list-keywords] is a list of all the lambda-list
keywords used in the implementation, including the additional ones
used only by @Macref[defmacro].  This list must contain at least the symbols
@optional, @rest, @key, @allowotherkeys, @aux, @body, @whole,
and @f[&environment].
@Enddefcon


As an example of the use of @allowotherkeys and @Kwd[allow-other-keys],
consider a function that takes two keyword arguments of its own and also
accepts additional keyword arguments to be passed to @Funref[make-array]:
@lisp
(defun array-of-strings (str dims @rest keyword-pairs
                         @key (start 0) end @allowotherkeys)
  (apply #'make-array dims
         :initial-element (subseq str start end)
         :allow-other-keys t
	 keyword-pairs))
@endlisp
This function takes a string and dimensioning information and returns
an array of the specified dimensions, each of whose elements is the
specified string.  However, @Kwd[start] and @Kwd[end] keyword arguments
may be used in the usual manner (see chapter @ref[KSEQUE]) to specify
that a substring of the given string should be used.  In addition,
the presence of @allowotherkeys in the lambda-list indicates that the caller
may specify additional keyword arguments; the @rest argument provides
access to them.  These additional keyword arguments are fed to @f[make-array].
Now @f[make-array] normally does not allow the keywords @Kwd[start]
and @Kwd[end] to be used, and it would be an error to specify such
keyword arguments to @f[make-array].  However, the presence in the
call to @f[make-array] of the keyword argument @Kwd[allow-other-keys]
with a non-@false value causes any extraneous keyword arguments,
including @Kwd[start] and @Kwd[end], to be acceptable and ignored.


@Defcon[Var {lambda-parameters-limit⎇]
The value of @f[lambda-parameters-limit] is a positive integer that is
the upper exclusive bound on the number of distinct parameter names
that may appear in a single lambda-list.
This bound depends on the implementation
but will not be smaller than 50.
Implementors are encouraged to make this limit as large as practicable
without sacrificing performance.
See @conref[call-arguments-limit].
@Enddefcon

@Section[Top-Level Forms]

The standard way for the user to interact with a @clisp implementation is
via a @i[read-eval-print loop]: the system repeatedly
reads a form from some input source (such as a keyboard or a disk file),
evaluates it, and then prints the value(s) to some output sink (such as a
display screen or another disk file).  Any form (evaluable
data object) is acceptable; however, certain special forms are specifically
designed to be convenient for use as @i[top-level] forms,
rather than as forms embedded within other forms in the way
that @f[(+ 3 4)]
is embedded within @f[(if p (+ 3 4) 6)].
These top-level special forms may be used to define globally named
functions, to define macros, to make declarations,
and to define global values for special variables.

It is not illegal to use these forms at other than top level,
but whether it is meaningful to do so depends on context.
Compilers, for example, may not recognize these forms properly
in other than top-level contexts.  (As a special case, however,
if a @Specref[progn] form appears at top level, then all forms
within that @f[progn] are considered by the compiler to be top-level
forms.)
@Incompatibility{In @maclisp, a top-level @f[progn] is considered to
contain top-level forms only if the first form is @f[(quote compile)].
This odd marker is unnecessary in @clisp.⎇

Macros are usually defined by using the special form @Macref[defmacro].
This facility is fairly complicated, and is described in chapter @Ref[MACROS].

@Subsection[Defining Named Functions]

The @f[defun] special form is the usual means of defining named functions.

@Defmac[Fun {defun⎇, Args {@i[name] @i[lambda-list] @Mstar<@i[declaration] @mor @i[doc-string]> @Mstar<@i[form]>⎇]
Evaluating a @f[defun] form causes the symbol @i[name] to be a global name
for the function specified by the lambda-expression
@Lisp
(lambda @i[lambda-list] @Mstar<@i[declaration] @mor @i[doc-string]> @Mstar<@i[form]>)
@Endlisp
defined in the lexical environment in which the @f[defun] form was
executed.  Because @f[defun] forms normally appear at top level, this is
normally the null lexical environment.

If the optional documentation string @i[doc-string] is present,
then it is attached to the @i[name]
as a documentation string of type @f[function]; see @Funref[documentation].
If @i[doc-string] is not
followed by a declaration, it may be
present only if at least one @i[form] is also specified, as it is
otherwise taken to be a @i[form].
It is an error if more than one @i[doc-string] is present.

The @i[forms] constitute the body of the defined function; they are
executed as an implicit @f[progn].

The body of the defined function is implicitly enclosed
in a @Specref[block] construct whose name is the same as the @i[name]
of the function.  Therefore @Specref[return-from]
may be used to exit from the function.

Other implementation-dependent bookkeeping actions may be taken as well
by @f[defun].  The @i[name] is returned as the value of the @f[defun]
form.
For example:
@lisp
(defun discriminant (a b c)
  (declare (number a b c))
  "Compute the discriminant for a quadratic equation.
   Given a, b, and c, the value b↑2-4*a*c is calculated.
   The quadratic equation a*x↑2+b*x+c=0 has real, multiple,
   or complex roots depending on whether this calculated
   value is positive, zero, or negative, respectively."
  (- (* b b) (* 4 a c)))
   @EV discriminant
   @r[and now] (discriminant 1 2/3 -2) @EV 76/9
@Endlisp
It is permissible to use @f[defun] to redefine a function,
to install a corrected version of an incorrect definition, for example!
It is permissible to redefine a macro as a function.
It is an error to attempt to redefine the name of a special
form (see Table @ref[SPECIAL-FORM-TABLE]) as a function.
@Enddefmac

@Subsection[Declaring Global Variables and Named Constants]

The @f[defvar] and @f[defparameter] special forms are
the usual means of specifying globally defined variables.
The @f[defconstant] special form is used for defining named constants.

@Defmac[Fun {defvar⎇, Args {@i[name] @Mopt<@i[initial-value] @Mopt'@i[documentation]'>⎇]
@Defmac1[Fun {defparameter⎇, Args {@i[name] @i[initial-value] @Mopt<@i[documentation]>⎇]
@Defmac1[Fun {defconstant⎇, Args {@i[name] @i[initial-value] @Mopt<@i[documentation]>⎇]
@f[defvar] is the recommended way to declare the use
of a special variable in a program.
@Lisp
(defvar @i[variable])
@Endlisp
proclaims @i[variable] to be @f[special] (see @Funref[proclaim]),
and may perform other system-dependent bookkeeping actions.
If a second ``argument'' is supplied,
@Lisp
(defvar @i[variable] @i[initial-value])
@Endlisp
then @i[variable] is initialized to the result of evaluating the form
@i[initial-value] unless it already has a value.  The @i[initial-value] form
is not evaluated unless it is used; this fact is useful if
evaluation of the @i[initial-value] form does something
expensive like creating a large data structure.  The initialization is
performed by assignment, and so assigns a global value to the variable
unless there are currently special bindings of that variable.
Normally there should not be any such special bindings.

@f[defvar] also provides a good place to put a comment describing the
meaning of the variable, whereas an ordinary @f[special] proclamation
offers the
temptation to declare several variables at once and not have room to
describe them all.
@Lisp
(defvar *visible-windows* 0
  "Number of windows at least partially visible on the screen")
@Endlisp

@f[defparameter] is similar to @f[defvar], but @f[defparameter] requires
an @i[initial-value] form, always evaluates the form, and assigns the
result to the variable.  The semantic distinction is that @f[defvar]
is intended to declare a variable changed by the program, whereas
@f[defparameter] is intended to declare a variable that is normally
constant but can be changed (possibly at run time), where such a change
is considered a
change @i[to] the program.  @f[defparameter] therefore does not indicate
that the quantity @i[never] changes; in particular, it does not license
the compiler to build assumptions about the value into programs being
compiled.

@f[defconstant] is like @f[defparameter] but @i[does] assert that
the value of the variable @i[name] is fixed and does license
the compiler to build assumptions about the value into programs being
compiled.  (However, if the compiler chooses to replaces references
to the name of the constant by the value of the constant in code
to be compiled, perhaps in order to allow further optimization,
the compiler must take care that such ``copies'' appear to be @f[eql]
to the object that is the actual value of the constant.  For example,
the compiler may freely make copies of numbers but must exercise
care when the value is a list.)

It is an error if there are any special bindings
of the variable at the time the @f[defconstant] form
is executed (but implementations may or may not check for this).

Once a name has been declared by @f[defconstant] to be constant,
any further assignment to or binding of that special variable is an error.
This is the case for such system-supplied constants as @Conref[t] and
@Conref[most-positive-fixnum].
A compiler may also choose to issue warnings about bindings of
the lexical variable of the same name.

For any of these constructs,
the documentation should be a string.  The string is attached
to the name of the variable, parameter, or constant
under the @f[variable] documentation type; see the @Funref[documentation]
function.

These constructs are normally used only as top-level forms.  The
value returned by each of these constructs is the @i[name] declared.
@Enddefmac

@Subsection[Control of Time of Evaluation]

The @f[eval-when] special form allows pieces of code to
be executed only at compile time, only at load time, or
when interpreted but not compiled.  Its uses are relatively esoteric.

@Defspec[Fun {eval-when⎇, Args {(@mstar<@i[situation]>) @mstar<@i[form]>⎇]
The body of an @f[eval-when] form is processed as an implicit
@f[progn], but only in the situations listed.  Each @i[situation]
must be a symbol, either @f[compile], @f[load], or @f[eval].

@f[eval] specifies that the interpreter should process the body.
@f[compile] specifies that the compiler should evaluate the body
at compile time in the compilation context.
@f[load] specifies that the compiler should arrange to evaluate
the forms in the body when the compiled file containing the
@f[eval-when] form is loaded.

The @f[eval-when] construct may be more precisely understood in terms
of a model of how the compiler processes forms in a file to
be compiled.  Successive forms are read from the file using the
function @Funref[read].
These top-level forms are normally processed in what we shall call
@i[not-compile-time] mode.  There is another mode called @i[compile-time-too]
mode.  The @f[eval-when] special form controls which of these two
modes to use.

Every form is processed as follows:
@Begin[Itemize]
@Begin[Multiple]
If the form is an @f[eval-when] form:
@Begin[Itemize]
@Begin[Multiple]
If the situation @f[load] is specified:
@Begin[Itemize]
If the situation @f[compile] is also specified, @i[or] if the
current processing mode is @i[compile-time-too] and the situation @f[eval]
is also specified, then process each of the forms in the body
in @i[compile-time-too] mode.

Otherwise, process each of the forms in the body in @i[not-compile-time] mode.
@End[Itemize]
@End[Multiple]

@Begin[Multiple]
If the situation @f[load] is not specified:
@Begin[Itemize]
If the situation @f[compile] is also specified, @i[or] if the
current processing mode is @i[compile-time-too] and the situation @f[eval]
is also specified, then evaluate each of the forms in the body
in the compiler's executing environment.

Otherwise, ignore the @f[eval-when] form entirely.
@End[Itemize]
@End[Multiple]
@End[Itemize]
@End[Multiple]

@Begin[Multiple]
If the form is not an @f[eval-when] form, then do two things.
First, if the current processing mode is @i[compile-time-too] mode,
then evaluate the form in the compiler's executing environment.
Second, perform normal compiler processing of the form
(compiling functions defined by @f[defun] forms, and so on).
@End[Multiple]
@End[Itemize]

One example of the use of @f[eval-when] is that
if the compiler is to be able to properly read a file
that uses user-defined reader macro characters,
it is necessary to write
@lisp
(eval-when (compile load eval)
  (set-macro-character #\$ #'(lambda (stream char)
			       (declare (ignore char))
			       (list 'dollar (read stream)))))
@endlisp
This causes the call to @Funref[set-macro-character] to be executed
in the compiler's execution environment, thereby modifying its
reader syntax table.
@Enddefspec